home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / RCS / Opt.man,v < prev    next >
Text File  |  1991-01-28  |  12KB  |  365 lines
  1. head     1.4;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.4
  10. date     91.01.28.17.00.56;  author kupfer;  state Exp;
  11. branches ;
  12. next     1.3;
  13.  
  14. 1.3
  15. date     91.01.28.16.52.37;  author kupfer;  state Exp;
  16. branches ;
  17. next     1.2;
  18.  
  19. 1.2
  20. date     89.01.20.13.57.04;  author ouster;  state Exp;
  21. branches ;
  22. next     1.1;
  23.  
  24. 1.1
  25. date     88.12.30.14.34.38;  author ouster;  state Exp;
  26. branches ;
  27. next     ;
  28.  
  29.  
  30. desc
  31. @@
  32.  
  33.  
  34. 1.4
  35. log
  36. @Add warning that OPT_TIME can clobber localtime's return area.
  37. @
  38. text
  39. @'\" Copyright 1991 Regents of the University of California
  40. '\" Permission to use, copy, modify, and distribute this
  41. '\" documentation for any purpose and without fee is hereby
  42. '\" granted, provided that this notice appears in all copies.
  43. '\" The University of California makes no representations about
  44. '\" the suitability of this material for any purpose.  It is
  45. '\" provided "as is" without express or implied warranty.
  46. '\" 
  47. '\" $Header: /sprite/src/lib/c/etc/RCS/Opt.man,v 1.3 91/01/28 16:52:37 kupfer Exp Locker: kupfer $ SPRITE (Berkeley)
  48. '/" 
  49. .so \*(]ltmac.sprite
  50. .HS Opt lib
  51. .BS
  52. .SH NAME
  53. Opt_Parse, Opt_PrintUsage \- Manage command line options
  54. .SH SYNOPSIS
  55. \fB#include <option.h>\fR
  56. .sp
  57. int
  58. \fBOpt_Parse\fR(\fIargc, argv, optionArray, numOptions, flags\fR)
  59. .sp
  60. void
  61. \fBOpt_PrintUsage\fR(\fIcommandName, optionArray, numOptions\fR)
  62. .SH ARGUMENTS
  63. .AS Option *optionArray
  64. .AP int argc in
  65. Number of arguments on command line.
  66. .AP char **argv in/out
  67. Command line arguments passed to main program.
  68. .AP char *commandName in
  69. Name of the program being run, usually \fIargv\fR[0].
  70. .AP Option *optionArray in
  71. An array of option descriptions.
  72. .AP int numOptions in
  73. Number of elements in optionArray, usually obtained using the
  74. \fBOpt_Number\fR macro, e.g. \fBOpt_Number\fR(optionArray).
  75. .AP int flags in
  76. If non-zero, then it specifies one or more flags that control the
  77. parsing of arguments.  Different flags may be OR'ed together.  The
  78. only flags currently defined are OPT_ALLOW_CLUSTERING and OPT_OPTIONS_FIRST.  
  79. .BE
  80. .SH DESCRIPTION
  81. .PP
  82. \fBOpt_Parse\fR parses the command line arguments of a program according
  83. to an array of option descriptions.  Starting with \fIargv\fR[1], it parses
  84. as many options as it can and returns the rest of the options in
  85. the \fIargv\fR array, compacted to the beginning of the array (starting
  86. with \fIargv\fR[1]).  The return value indicates how many options are
  87. returned in the \fIargv\fR array (including \fIargv\fR[0]).
  88. Opt_Parse returns options that don't start with ``-'' unless they
  89. are arguments for options that it parses.  \fBOpt_Parse\fR also returns
  90. any options following an \fBOPT_REST\fR option (see below for more details).
  91. .PP
  92. Each element of the array
  93. \fIoptionArray\fR has the following structure:
  94. .DS
  95. .ta 2c
  96. \fBtypedef struct\fR Option {
  97.     \fBint\fR    \fItype\fR;
  98.     \fBchar\fR    *\fIkey\fR;
  99.     \fBchar\fR    *\fIvaluePtr\fR;
  100.     \fBchar\fR    *\fIdocMsg\fR;
  101. } Option;
  102. .DE
  103. .LP
  104. The \fIkey\fR field is a string that identifies this option.  For
  105. example, if \fIkey\fR is \fBfoo\fR, then this Option will match
  106. a \fB\-foo\fR command-line option.  If \fIkey\fR is the empty
  107. string (``'') then it matches a \fB\-\fR command-line option.
  108. If \fIkey\fR is NULL, the Option
  109. will not match any command-line options (this feature is only useful
  110. for OPT_DOC options).
  111. \fIDocMsg\fR is a documentation string to print out as part of a
  112. help message.
  113. The \fItype\fR field determines what to do when this Option is
  114. matched.  It also determines the meaning of the \fIvaluePtr\fR
  115. field.  \fIType\fR should always be specified using one of the
  116. following macros:
  117. .TP
  118. \fBOPT_TRUE\fR
  119. Treats \fIvaluePtr\fR as the address of an integer, and stores
  120. the value 1 in that integer.
  121. .TP
  122. \fBOPT_FALSE\fR
  123. Treats \fIvaluePtr\fR as the address of an integer and stores
  124. the value 0 in that integer.
  125. .TP
  126. \fBOPT_CONSTANT\fR(\fIvalue\fR)
  127. This is a generalized form of OPT_TRUE and OPT_FALSE.  Treats
  128. \fIvaluePtr\fR as the address of an integer and stores \fIvalue\fR
  129. in that integer.  \fIValue\fR must be a positive integer.
  130. .TP
  131. \fBOPT_INT\fR
  132. The next argument after the one matching \fIkey\fR must contain an
  133. integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
  134. and ``0x'' prefixes may be used to specify octal or hexadecimal
  135. numbers, respectively).  \fIValuePtr\fR
  136. will be treated as the address of an integer, and the value given
  137. by the next argument will be stored there.
  138. .TP
  139. \fBOPT_TIME\fR
  140. The next argument after the one matching \fIkey\fR must contain a
  141. string that is parsable as a date and time.  Currently, only two
  142. formats are recognized:
  143. .DS
  144. \fIseconds\fR
  145. .DE
  146. .IP
  147. and
  148. .DS
  149. \fIyy\fB.\fImm\fB.\fIdd\fB.\fIhh\fB.\fImm\fB.\fIss\fR
  150. .DE
  151. .IP
  152. The first form is simply the number of seconds since the start of the
  153. epoch (1 January 1970, 0 hours GMT).  The second form specifies the
  154. year (e.g., 91 or 1991),
  155. month (1-12), day of the month, hours (0-23), minutes (0-59), and
  156. seconds (0-59).  All fields must be specified.
  157. \fIValuePtr\fR
  158. will be treated as the address of a
  159. .B time_t
  160. (defined in
  161. .BR <time.h> ), 
  162. and the given time will be stored there.
  163. All times are in terms of the current timezone and daylight savings
  164. rules.
  165. .IP
  166. Note that this flavor can clobber the static buffer used by the 
  167. .B localtime
  168. library routine.
  169. .TP
  170. \fBOPT_FLOAT\fR
  171. The next argument after the one matching \fIkey\fR must contain a
  172. floating-point number in the format accepted by \fBstrtol\fR.
  173. \fIValuePtr\fR will be treated as the address of an double-precision
  174. floating point value, and the
  175. value given by the next argument will be stored there.
  176. .TP
  177. \fBOPT_STRING\fR
  178. Treats \fIvaluePtr\fR as the address of a (char *), and stores a pointer
  179. to the next argument in the location
  180. pointed to by \fIvaluePtr\fR.
  181. .TP
  182. \fBOPT_DOC\fR
  183. This option is intended primarily as a way of printing extra documentation
  184. during help message printouts.  It isn't normally used as an actual
  185. option (and normally its \fIkey\fR field is NULL).
  186. If it is invoked as an option, then the same thing happens as for
  187. the ``-?'' option:  descriptions get printed for all options in
  188. \fIoptionArray\fR and \fBOpt_Parse\fR calls exit(0) to terminate the process.
  189. .TP
  190. \fBOPT_REST\fR
  191. This option is used by programs that allow the last several of their
  192. options to be the name and/or options for some other program.  If
  193. an \fBOPT_REST\fR option is found, then \fBOpt_Parse\fR doesn't process any
  194. of the remaining arguments;  it returns them all at the beginning of \fIargv\fR.
  195. In addition, \fBOpt_Parse\fR treats \fIvaluePtr\fR as the address of an
  196. integer value, and stores in that value the index of the first of the
  197. \fBOPT_REST\fR options in the returned \fIargv\fR.  This allows the
  198. program to distinguish the \fBOPT_REST\fR options from other
  199. unprocessed options that preceeded the \fBOPT_REST\fR.
  200. .TP
  201. \fBOPT_FUNC\fR
  202. When one of these options is encountered, \fIvaluePtr\fR is treated
  203. as the address of a function which is then called
  204. with the following calling sequence:
  205. .DS
  206. .ta 1c 2c 3c 4c 5c 6c
  207. \fBint\fI
  208. func(optString, nextArg)
  209.     \fBchar\fR    *\fIoptString\fR;
  210.     \fBchar\fR    *\fInextArg\fR;
  211. {
  212. }
  213. .DE
  214. .IP
  215. The \fIoptString\fR parameter points to the current option, and
  216. \fInextArg\fR points to the next option from \fIargv\fR (or NULL
  217. if there aren't any more options in \fIargv\fR.  If \fIfunc\fR
  218. uses \fInextArg\fR as an argument to the current option (so that
  219. Opt_Parse should skip it), then it should return 1.  Otherwise it
  220. should return 0.
  221. .TP
  222. \fBOPT_GENFUNC\fR
  223. Treat \fIvaluePtr\fR as the address of a function and pass all of the
  224. remaining arguments to it in the following way:
  225. .DS
  226. .ta 1c 2c 3c 4c 5c 6c
  227. \fBint\fI
  228. genfunc(optString, argc, argv)
  229.     \fBchar\fR    *\fIoptString\fR;
  230.     \fBint\fR    \fIargc\fR;
  231.     \fBchar\fR    **\fIargv\fR;
  232. {
  233. }
  234. .DE
  235. .IP
  236. \fIArgc\fR and \fIargv\fR refer to all of the options after the
  237. one that triggered the call, and \fIoptString\fR points to the
  238. triggering option.  \fIGenfunc\fR should behave in a fashion similar
  239. to \fBOpt_Parse\fR:  parse as many of the remaining arguments as it can,
  240. then return any that are left by compacting them to the beginning of
  241. \fIargv\fR (starting at \fIargv\fR[0]).  \fIGenfunc\fR
  242. should return a count of how many arguments are left in \fIargv;
  243. \fBOpt_Parse\fR will process them.
  244.  
  245. .SH "FLAGS"
  246. .IP \fBOPT_ALLOW_CLUSTERING\fR
  247. This will
  248. permit several options to be clustered together with a
  249. single ``-'', e.g., ``foo -abc'' will be handled the same way as
  250. ``foo -a -b -c''.  OPT_ALLOW_CLUSTERING is likely to cause confusing
  251. behavior unless each option is identified with a single character.
  252. .IP \fBOPT_OPTIONS_FIRST\fR
  253. This causes \fBOpt_Parse\fR to stop parsing the command line anytime something
  254. that is not an option is detected.  Thus, a program that takes some options 
  255. followed by a command to execute (along with that command's options) can 
  256. parse its own options using OPT_OPTIONS_FIRST.  When the command to execute is 
  257. encountered, assuming it does not begin with a hyphen, \fBOpt_Parse\fR will 
  258. return the command and its arguments starting at \fIargv\fR[1], ignoring
  259. any arguments with hyphens following the first non-option.
  260. .SH "USAGE MESSAGE"
  261. .PP
  262. \fBOpt_PrintUsage\fR may be invoked to print out all the documentation strings
  263. (plus option names and default values) for a command's options.  If
  264. \fBOpt_Parse\fR encounters an option ``-?'' or ``-help'', then it will call
  265. \fBOpt_PrintUsage\fR
  266. and exit.  Note:  in some shells the question-mark must be escaped
  267. (e.g., ``foo -\e?'' in \fIcsh\fR).
  268.  
  269. .SH EXAMPLE
  270. .PP
  271. Here is an example definition of a set of option descriptions and
  272. some sample command lines that use the options.  Note the effect
  273. on argc and argv;  command arguments that get interpreted as
  274. options or option values are eliminated from argv, and argc
  275. is updated to reflect reduced number of arguments.
  276. .DS
  277. /*
  278.  * Define and set default values for globals.
  279.  */
  280. Boolean debugFlag = FALSE;
  281. int numReps = 100;
  282. char defaultFileName[] = "out";
  283. char *fileName = defaultFileName;
  284. Boolean exec = FALSE;
  285.  
  286. /*
  287.  * Define option descriptions.
  288.  */
  289. Option optionArray[] = {
  290.     OPT_TRUE, "X", (char *) &debugFlag, "Turn on debugging printfs",
  291.     OPT_INT, "N", (char *) &numReps, "Number of repetitions",
  292.     OPT_STRING, "of", (char *) &fileName, "Output filename",
  293.     OPT_REST, "x", (char *) &exec,
  294.         "File to exec, followed by any arguments (must be last argument).",
  295. };
  296.  
  297. main(argc, argv)
  298.     int argc;
  299.     char *argv[];
  300. {
  301.     Opt_Parse(argc, argv, optionArray, Opt_Number(optionArray),
  302.             OPT_ALLOW_CLUSTERING);
  303.  
  304.     /*
  305.      * the rest of the program.
  306.      */
  307. }
  308. .DE
  309. .PP
  310. Note that default values can be assigned to option variables.
  311. Also, numOptions gets calculated by the compiler in this example.
  312. Here are some example command lines and their effects.
  313. .DS
  314. prog -N 200 infile        # just sets the numReps variable to 200
  315. prog -of out200 infile     # sets fileName to reference "out200"
  316. prog -XN 10 infile        # sets the debug flag, also sets numReps
  317. .DE
  318. In all of the above examples, the return value from Opt_Parse will be 2,
  319. \fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
  320. and \fIargv\fR[2] will be NULL.
  321.  
  322. .SH KEYWORDS
  323. arguments, command line, options
  324. @
  325.  
  326.  
  327. 1.3
  328. log
  329. @Add OPT_TIME flavor.
  330. @
  331. text
  332. @d9 1
  333. a9 1
  334. '\" $Header: /sprite/lib/forms/RCS/lib.man,v 1.3 91/01/07 17:55:52 mottsmth Exp $ SPRITE (Berkeley)
  335. d127 4
  336. @
  337.  
  338.  
  339. 1.2
  340. log
  341. @Clean up format.
  342. @
  343. text
  344. @d1 10
  345. a10 1
  346. ' $Header: /sprite/src/lib/c/etc/RCS/Opt.man,v 1.1 88/12/30 14:34:38 ouster Exp Locker: ouster $ SPRITE (Berkeley)
  347. d100 27
  348. @
  349.  
  350.  
  351. 1.1
  352. log
  353. @Initial revision
  354. @
  355. text
  356. @d1 1
  357. a1 1
  358. ' $Header: /sprite/doc/ref/lib/c/RCS/Opt_Parse,v 1.9 88/11/19 16:53:53 douglis Exp Locker: douglis $ SPRITE (Berkeley)
  359. d6 1
  360. a6 3
  361. Opt_Parse \- Parse command line options
  362. .br
  363. Opt_PrintUsage \- Print a usage message for a command
  364. @
  365.